HAL SD interrupt handler and callbacks

This section provides information about HAL SD interrupt handling and callbacks for STM32 HAL1 to HAL2 migration.

HAL SD callbacks

Callback functions signatures and handling remain largely the same between HAL1 and HAL2. Except for the transfer complete callbacks which have been consolidated into a single callback with an additional parameter to specify the event type, and the transceiver callback which takes the handle as parameter in HAL2 and an update with new HAL SD type to specify the transceiver state.

HAL1

HAL2 

void HAL_SD_TxCpltCallback(SD_HandleTypeDef *hsd)
void HAL_SD_RxCpltCallback(SD_HandleTypeDef *hsd)
void HAL_SDEx_Read_DMALnkLstBufCpltCallback(SD_HandleTypeDef *hsd)
void HAL_SDEx_Write_DMALnkLstBufCpltCallback(SD_HandleTypeDef *hsd)

void HAL_SD_ErrorCallback(SD_HandleTypeDef *hsd)

void HAL_SD_AbortCallback(SD_HandleTypeDef *hsd)

void HAL_SD_DriveTransceiver_1_8V_Callback(FlagStatus status)

void HAL_SD_XferCpltCallback(hal_sd_handle_t *hsd,
                             hal_sd_event_cb_t cb_event)



void HAL_SD_ErrorCallback(hal_sd_handle_t *hsd)

void HAL_SD_AbortCallback(hal_sd_handle_t *hsd)

void HAL_SD_DriveTransceiver_1_8V_Callback(hal_sd_handle_t *hsd,
                                hal_sd_transceiver_state_t state)

HAL SD linked-list DMA callback macro aliases

HAL1

HAL2 

void HAL_SDEx_DMALinkedList_ReadCpltCallback(SD_HandleTypeDef *hsd)
void HAL_SDEx_DMALinkedList_WriteCpltCallback(SD_HandleTypeDef *hsd)

Removed; use HAL_SD_XferCpltCallback() instead.

Note

  • In HAL1, these extended API callbacks are simple aliases to HAL_SD_TxCpltCallback() and HAL_SD_RxCpltCallback() respectively.

  • In HAL2, use HAL_SD_XferCpltCallback() with the event type parameter set to either HAL_SD_EVENT_CB_TX_CPLT or HAL_SD_EVENT_CB_RX_CPLT to distinguish between transfer directions.

HAL SD DMA multi-buffer callbacks

HAL1

HAL2 

void HAL_SDEx_Read_DMADoubleBuf0CpltCallback(SD_HandleTypeDef *hsd)
void HAL_SDEx_Read_DMADoubleBuf1CpltCallback(SD_HandleTypeDef *hsd)
void HAL_SDEx_Write_DMADoubleBuf0CpltCallback(SD_HandleTypeDef *hsd)
void HAL_SDEx_Write_DMADoubleBuf1CpltCallback(SD_HandleTypeDef *hsd)

Multi-buffering is available only in some STM32 series. These series are not yet supported in HAL2.

HAL SD transceiver callback registration

HAL1

HAL2 

HAL_StatusTypeDef HAL_SD_RegisterTransceiverCallback(SD_HandleTypeDef *hsd,
                                 pSD_TransceiverCallbackTypeDef pCallback)

hal_status_t HAL_SD_RegisterTransceiverCallback(hal_sd_handle_t *hsd,
                                    hal_sd_transceiver_cb_t callback)

HAL SD callback registration

HAL1

HAL2

In HAL1, the function HAL_SD_RegisterCallback is used to register SD callbacks using a single function with a specific callback ID.

In HAL2, separate functions are available to register each specific SD callback. The MSP init and deinit callbacks are removed; users must handle hardware initialization and deinitialization manually, refer to Initialization and de-initialization seuquence for more details.

Examples of migrating the callbacks registration

HAL1

HAL2 

 HAL_SD_RegisterCallback(hsd,
                   HAL_SD_TX_CPLT_CB_ID,
                   USER_SD_TxCpltCallback)

 HAL_SD_RegisterCallback(hsd,
                   HAL_SD_RX_CPLT_CB_ID,
                   USER_SD_RxCpltCallback)

 HAL_SD_RegisterCallback(hsd,
       HAL_SD_READ_DMA_LNKLST_BUF_CPLT_CB_ID,
       USER_SD_ReadDMALnkLstBufCpltCallback)

HAL_StatusTypDef HAL_SD_RegisterCallback(hsd,
       HAL_SD_WRITE_DMA_LNKLST_BUF_CPLT_CB_ID,
       USER_SD_WriteDMALnkLstBufCpltCallback)

HAL_SD_RegisterXferCpltCallback(hsd,
                   USER_SD_XferCpltCallback)

Note

One event callback function handles all transfer complete events with an additional parameter to specify the event type. 

HAL_SD_RegisterCallback(hsd,
                   HAL_SD_ERROR_CB_ID,
                   USER_SD_ErrorCallback)

HAL_SD_RegisterErrorCallback(hsd,
                   USER_SD_ErrorCallback)

HAL_SD_RegisterCallback(hsd,
                   HAL_SD_ABORT_CB_ID,
                   USER_SD_AbortCallback)

HAL_SD_RegisterAbortCallback(hsd,
                   USER_SD_AbortCallback)

HAL_SD_RegisterCallback(hsd,
                   HAL_SD_ABORT_CB_ID,
                   USER_SD_AbortCallback)

HAL_SD_RegisterAbortCallback(hsd,
                   USER_SD_AbortCallback)

HAL_SD_RegisterCallback(hsd,
        HAL_SD_READ_DMA_DBL_BUF0_CPLT_CB_ID,
        USER_SD_ReadDMADblBuf0CpltCallback)

HAL_SD_RegisterCallback(hsd,
        HAL_SD_READ_DMA_DBL_BUF1_CPLT_CB_ID,
        USER_SD_ReadDMADblBuf1CpltCallback)

HAL_SD_RegisterCallback(hsd,
       HAL_SD_WRITE_DMA_DBL_BUF0_CPLT_CB_ID,
       USER_SD_WriteDMADblBuf0CpltCallback)

HAL_SD_RegisterCallback(hsd,
       HAL_SD_WRITE_DMA_DBL_BUF1_CPLT_CB_ID,
       USER_SD_WriteDMADblBuf1CpltCallback)

Multi-buffering is available only in some STM32 series. These series are not yet supported in HAL2. 

HAL_SD_RegisterCallback(hsd,
                   HAL_SD_MSP_DEINIT_CB_ID,
                   USER_SD_MspDeInitCallback)

HAL_SD_RegisterCallback(hsd,
                     HAL_SD_MSP_INIT_CB_ID,
                     USER_SD_MspInitCallback)

Removed; The MSP init and deinit callbacks are removed. Users must handle hardware initialization and deinitialization in application code. Refer to Initialization and de-initialization seuquence for more details.

Related concepts:

HAL SD callback unregistration

HAL1

HAL2

In HAL1, the function HAL_SD_UnRegisterTransceiverCallback is used to unregister the SD voltage transceiver callback.

In HAL2, unregister APIs are removed, user can simply register the default weak callback using the appropriate HAL SD register callback APIs.

Examples of migrating the transceiver callback registration

HAL1

HAL2 

HAL_SD_UnRegisterTransceiverCallback(hsd,
                       USER_SD_TransceiverCallback)

HAL_SD_RegisterTransceiverCallback(hsd,
                       HAL_SD_DriveTransceiver_1_8V_Callback)

HAL SD callback unregistration

HAL1

HAL2

In HAL1, the function HAL_SD_UnRegisterCallback is used to unregister SD callbacks using a single function with a specific callback ID.

In HAL2, unregister APIs are removed, user can simply register the default weak callback using the HAL SD register callback APIs.

Examples of migrating the callbacks registration

HAL1

HAL2 

HAL_SD_UnRegisterCallback(hsd,
                        HAL_SD_TX_CPLT_CB_ID,
                        USER_SD_TxCpltCallback)

HAL_SD_UnRegisterCallback(hsd,
                        HAL_SD_RX_CPLT_CB_ID,
                        USER_SD_RxCpltCallback)

HAL_SD_UnRegisterCallback(hsd,
         HAL_SD_READ_DMA_LNKLST_BUF_CPLT_CB_ID,
         USER_SD_ReadDMALnkLstBufCpltCallback)

HAL_SD_UnRegisterCallback(hsd,
        HAL_SD_WRITE_DMA_LNKLST_BUF_CPLT_CB_ID,
        USER_SD_WriteDMALnkLstBufCpltCallback)

HAL_SD_RegisterXferCpltCallback(hsd,
                        HAL_SD_XferCpltCallback)

Note

One event callback function handles all transfer complete events with an additional parameter to specify the event type. 

HAL_SD_UnRegisterCallback(hsd,
                         HAL_SD_ERROR_CB_ID,
                         USER_SD_ErrorCallback)

HAL_SD_RegisterErrorCallback(hsd,
                        HAL_SD_ErrorCallback)

HAL_SD_UnRegisterCallback(hsd,
                         HAL_SD_ABORT_CB_ID,
                         USER_SD_AbortCallback)

HAL_SD_RegisterAbortCallback(hsd,
                        HAL_SD_AbortCallback)

HAL_SD_UnRegisterCallback(hsd,
        HAL_SD_READ_DMA_DBL_BUF0_CPLT_CB_ID,
        USER_SD_ReadDMADblBuf0CpltCallback)

HAL_SD_UnRegisterCallback(hsd,
        HAL_SD_READ_DMA_DBL_BUF1_CPLT_CB_ID,
        USER_SD_ReadDMADblBuf1CpltCallback)

HAL_SD_UnRegisterCallback(hsd,
       HAL_SD_WRITE_DMA_DBL_BUF0_CPLT_CB_ID,
       USER_SD_WriteDMADblBuf0CpltCallback)

HAL_SD_UnRegisterCallback(hsd,
       HAL_SD_WRITE_DMA_DBL_BUF1_CPLT_CB_ID,
       USER_SD_WriteDMADblBuf1CpltCallback)

Multi-buffering is available only in some STM32 series. These series are not yet supported in HAL2. 

HAL_SD_UnRegisterCallback(hsd,
                HAL_SD_MSP_DEINIT_CB_ID,
                USER_SD_MspDeInitCallback)

HAL_SD_UnRegisterCallback(hsd,
                 HAL_SD_MSP_INIT_CB_ID,
                 USER_SD_MspInitCallback)

Removed; The MSP init and deinit callbacks are removed. Users must handle hardware initialization and deinitialization in application code. Refer to Initialization and de-initialization seuquence for more details.

Related concepts:

HAL SD interrupt request handler

HAL1

HAL2 

void HAL_SD_IRQHandler(SD_HandleTypeDef *hsd)

void HAL_SD_IRQHandler(hal_sd_handle_t *hsd)